package de.jmda.core.dao;

import java.io.Serializable;
import java.util.Collection;


/**
 * Generic interface for data access objects (DAOs). Defines a set of operations
 * that are common to technology specific implementations of DAOs.
 * <p>
 * <b>This interface should not expose any implementation specifics!</b>
 *
 * @param <ENTITY_CLASS_TYPE> specifies the persistent class (entity class) for
 *                            which the implementing class provides DAO
 *                            operations
 * @param <ENTITY_CLASS_ID> specifies the persistent class's primary key class
 */
public interface GenericDAO<ENTITY_CLASS_TYPE extends Serializable,
                            ENTITY_CLASS_ID extends Serializable>
{
	/**
	 * Executes a find by <code>id</code> and returns the result (may be <code>
	 * null</code>). If <code>lock == true</code> and the find was successful the
	 * found object will be locked for update.
	 * <p>
	 * <b>Note:</b> Related objects are not loaded eagerly. Use {@link
	 * #findByIdWithRelated(Serializable, boolean)} if you need to access the
	 * returned object's relations.
	 *
	 * @param id
	 * @param lock
	 * @return see above
	 */
	ENTITY_CLASS_TYPE findById(ENTITY_CLASS_ID id, boolean lock)
			throws DAOException;

	/**
	 * Calls {@link #findById(Serializable, boolean)} with <code>lock == false
	 * </code>.
	 */
	ENTITY_CLASS_TYPE findById(ENTITY_CLASS_ID id) throws DAOException;

	/**
	 * Executes a find by <code>id</code> and returns the result (may be <code>
	 * null</code>). If <code>lock == true</code> and the find was successful the
	 * found object will be locked for update before return.
	 * <p>
	 * <b>Note:</b> Directly related objects are loaded eagerly! Use {@link
	 * #findById(Serializable, boolean)} if you do not need to access the returned
	 * object's relations.
	 *
	 * @param id
	 * @param lock
	 * @return see above
	 */
	ENTITY_CLASS_TYPE findByIdWithRelated(ENTITY_CLASS_ID id, boolean lock)
			throws DAOException;

	/**
	 * Calls {@link #findByIdWithRelated(Serializable, boolean)} with <code>lock
	 * == false</code>.
	 */
	ENTITY_CLASS_TYPE findByIdWithRelated(ENTITY_CLASS_ID id) throws DAOException;

	/**
	 * Executes a find all and returns the results.
	 * <p>
	 * <b>Note:</b> Related objects are not loaded eagerly.
	 *
	 * @return see above
	 */
	Collection<ENTITY_CLASS_TYPE> findAll() throws DAOException;

	/**
	 * Stores an object.
	 *
	 * @param entity
	 * @return see above
	 */
	ENTITY_CLASS_TYPE create(ENTITY_CLASS_TYPE entity) throws DAOException;

	/**
	 * Updates and returns the updated object.
	 *
	 * @param entity
	 * @return see above
	 */
	ENTITY_CLASS_TYPE update(ENTITY_CLASS_TYPE entity) throws DAOException;

	/**
	 * Executes a find by id and deletes the found object.
	 *
	 * @param id
	 */
	void delete(ENTITY_CLASS_ID id) throws DAOException;

	void flush() throws DAOException;

	void clear() throws DAOException;
}